Usenet 1993 July/InfoMagic USENET CD-ROM July 1993.ISO/sources/unix/volume18/elm2.2/part04

Internet Message Format | 1989-04-12 | 49.0 KB

Subject:  v18i083:  Elm mail system, release 2.2, Part04/24
Newsgroups: comp.sources.unix
Sender: sources
Approved: [e-mail]

Submitted-by: dsinc![e-mail] (Syd Weinstein)
Posting-number: Volume 18, Issue 83
Archive-name: elm2.2/part04

#!/bin/sh
# this is part 4 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file doc/Filter.guid continued
#
CurArch=4
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
     exit 1; fi
( read Scheck
  if test "$Scheck" != $CurArch
  then echo "Please unpack part $Scheck next!"
       exit 1;
  else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file doc/Filter.guid"
sed 's/^X//' << 'SHAR_EOF' >> doc/Filter.guid
X.sp 5
XDave Taylor
X.sp
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp 4
X.ps 18
X\f3\(co\f1\s12 Copyright 1986, 1987 by Dave Taylor
X.ps 18
X\f3\(co\f1\s12 Copyright 1988, 1989 by The USENET Community Trust
X.ps 10
X.bp 1
X.sp 5
X.ps 14
X\f3The Elm Filter System Guide\f1
X.ds h0 "Elm Filter Guide
X.ds h2 "Version 2.2
X.ds f0
X.ds f1 "Page %
X.sp
X.ps 10
X(Version 2.2)
X.sp 2
XDave Taylor
X.sp
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp 2
XApril 1, 1989
X.ce 0
X.sp 3
X.pg
XOne of the greatest problems with the burgeoning electronic mail
Xexplosion is that I tend to get lots of mail that I don't care about.
XAmusingly, perhaps, I have the equivalent of electronic junk mail.
XNot amusing, however, is the fact that this can rapidly
Xaccumulate and end up taking over my mailbox.
X.pg
XAt the same time I often get mail that, while it is interesting
Xand important, can easily be filed to be read later, without ever
Xactually having to cluttering up my incoming mailbox.
X.sp 2
XThis, then, is what \f2filter\f1 does!  The \f2filter\f1 program
Xallows you to define a set of rules by which all incoming mail should
Xbe screened, and a subsequent set of actions to perform based on whether
Xthe conditions were met or not.  \f2Filter\f1 also has the ability to mail
Xa summary of what actions it performed on the incoming mail as often as
Xyou'd like.
X.ne 5
X.hu Writing the Rules
X.sp
XThe language for writing \f2filter\f1 rules is pretty simple, actually.
XThe fundamental structure is;
X.nf
X.ti .5i
Xif  (\f2condition\f1)  then  \f2action\f1
X.fi
XWhere \f2condition\f1 is constructed by an arbitrary number of
Xindividual conditions of the form ``\f2field\f1  \f2relation\f1  \f2value\f1''.
X(an optional further type of rule is of the form ``always \f2action\f1''
Xbut should only be used as the last rule in the ruleset, for obvious
Xreasons).
XThe \f2field\f1 value can be;
X.nf
X.in .5i
Xsubject
Xfrom
Xto
Xlines
Xcontains
X.in 0
X.fi
Xwhere, if ``lines'' is chosen, the \f2relation\f1 can be any of the
Xstandard relationships (`>', `<', `>=', `<=', `!=' and `=').
XIf another action is
Xchosen, ``contains'' can be used as the relation, ``='', or, if you'd
Xlike, you can skip the relationship entirely (e.g. `subject "joe"').
XThe \f2value\f1 is any quoted string that is to be matched against
Xor number if ``lines'' is the field being considered.
X.sp
XIndividual conditions are joined together by using the word ``and'',
Xand the logic of a condition can be flipped by using ``not'' as the
Xfirst word (e.g. `not subject "joe"').  We'll see more examples of
Xthis later.
X.sp
XNote that the ``or'' logical conjunction isn't a valid part of the
X\f2filter\f1 conditional statement.
X.sp
XFinally, <\f2action\f1> can be any of;
X.nf
X.in .5i
Xdelete
Xsave   \f2foldername\f1
Xsavecopy  \f2foldername\f1
Xforward  \f2address\f1
Xexecute  \f2command\f1
Xleave
X.in 0
X.fi
Xwhere they result in the actions;  \f3delete\f1 deletes the message;
X\f3save\f1 saves a copy of the message in the specified foldername;
X\f3savecopy\f1 does the same as save, but also puts a copy in your mailbox;
X\f3forward\f1 sends the message to the specified address;
X\f3execute\f1 feeds the message to the specified command (or complex
Xsequence of commands) as standard input;
Xand \f3leave\f1 leaves the message in your mailbox.
X.sp
XFoldernames can contain any of a number of macros, too, as we'll see in
Xthe example ruleset below.  The macros available for the string fields are;
X.ft CW
X.TS
Xcenter;
Xlf3 lf3
Xl l.
XMacro    Meaning
X%d    day of the month
X%D    day of the week (0-6)
X%h    hour of the day (0-23)
X%m    month of the year (0-11)
X%r    return address of message
X%s    subject of original message
X%S    ``Re: \f2subject of original message\f1''
X.ft CW
X%t    current hour and minute in HH:MM format
X%y    year (last two digits)
X.TE
X.ft 1
X.sp
XThe rules file can also contain comments (any line starting with a `#')
Xand blank lines.
X.sp
XThe file itself needs to reside in your home directory and be
Xcalled \f2.filter-rules\f1.  Here's an example:\fC
X.nf
X # $HOME/.filter-rules
X #
X # Filter rules for the Elm Filter program. Don't change without some
X # serious thought. (remember - order counts)
X #
X # (for Dave Taylor)
X # rule 1
X if (from contains "!uucp") then delete
X # rule 2
X to "postmaster" ? save "/tmp/postmaster-mail.%d"
X # rule 3
X if (to "culture" and lines > 20) ? save "/users/taylor/Mail/culture"
X # rule 4
X subject = "filter test" ? forward "hpldat!test"
X # rule 5
X if [ subject = "elm" ] savecopy "/users/taylor/Mail/elm-incoming"
X # rule 6
X subject = "display-to-console" ? execute "cat - > /dev/console"
X.fi
X\f1(notice the loose syntax \(em there are lots of valid ways to specify a
Xrule in the \f2filter\f1 program!!)
X.sp
XTo translate these into English;
X.sp
X.nr TW \w'1. 'u
X.in .5i
X.ti -\n(TWu
X1. All messages from uucp should be summarily deleted.
X
X.ti -\n(TWu
X2. All mail to postmaster should be saved in a folder (file) called
X/tmp/postmaster-mail.\f2numeric-day-of-the-week\f1
X
X.ti -\n(TWu
X3. All mail addressed to `culture' with at least 20 lines
Xshould be automatically appended to the folder
X/users/taylor/Mail/culture.
X
X.ti -\n(TWu
X4. All messages that contain the subject `filter test' should be forwarded to
Xme, but via the address `hpldat!test' (to force a non-user forward)
X
X.ti -\n(TWu
X5. All messages with a subject that contains the word `elm' should be saved in
Xthe folder ``/users/taylor/Mail/elm-incoming'' and also dropped into my
Xmailbox.
X
X.ti -\n(TWu
X6. Any message with the subject ``display-to-console'' will be immediately
Xwritten to the console.
X.in 0
X.sp
XNotice that the \f2order\f1 of the rules is very important.  If we, for
Xexample, were to get a message from `uucp' that had the subject `filter test',
Xthe \f2filter\f1 program would match rule 1 and delete the message.  It
Xwould never be forwarded to `hpldat!test'.  It is for this reason that
Xgreat care should be taken with the ordering of the rules.
X.ne 5
X.hu Checking the rules out
X.sp
XThe \f2filter\f1 program has a convenient way of check out the rules you
Xhave written.  Simply invoke it with the \f3-r\f1 (\f3r\f1ules) flag;
X.nf
X.in .5i
X% \f3filter -r\f1
X.ft CW
X.in .5i+\w'Rule 1: 'u
X.ti .5i
XRule 1: if (from = "!uucp") then
XDelete
X.ti .5i
XRule 2: if (to = "postmaster") then
XSave  /tmp/postmaster-mail.<day-of-week>
X.ti .5i
XRule 3: if (to = "culture" and lines > 20) then
XSave  /users/taylor/Mail/culture
X.ti .5i
XRule 4: if (subject = "filter test") then
XForward  hpldat!test
X.ti .5i
XRule 5: if (subject="elm") then
XCopy  and  Save  /users/taylor/Mail/elm-incoming
X.ti .5i
XRule 6: if (subject="display-to-console") then
XExecute "cat - > /dev/console"\f1
X.ft 1
X.in 0
X.fi
X.sp
XThere are a few things to notice \(em first off, these are the parsed and
Xrebuilt rules, so we can see that they are all in a
Xconsistent format.  Also, notice on the filename for rule 2 that the
Xprogram has correctly expanded the ``%d'' macro to be the day of the
Xweek.
X.sp
XIt is \f3highly\f1 recommended that you always check your ruleset before
Xactually letting the program use it!
X.ne 5
X.hu Actually Using the Program
X.sp
XNow the bad news.  If you aren't running \f2sendmail\f1 you cannot use
Xthis program as currently written.  Why?  Because the \f2filter\f1
Xprogram expects to be put in your \f2.forward\f1 file and that is something
Xthat only \f2sendmail\f1 looks at!
X.sp
XThe format for the entry in the \f2.forward\f1 file (located in your
Xhome directory) is simply;
X.nf
X.ti .5i
X"| /usr/local/bin/filter"
X.fi
XAllright, it isn't quite \f2that\f1 simple!  Since \f2filter\f1 will be invoked
Xby processes that don't know where you are logged in, you need to have some
Xway to trap the error messages.  For ease of use, it was decided to have all
Xthe messages written to the file specified by `-o' (or \f2stderr\f1)
Xwhich means that you have two main
Xchoices for the actual entry.  Either;
X.nf
X.ti .5i
X"| /usr/local/bin/filter -o /dev/console"
X.fi
Xwhich will log all errors on the system console (each error is prefixed with
X``filter (\f2username\f1)'' to distinguish it), or;
X.nf
X.ti .5i
X"| /usr/local/bin/filter -o /tmp/joe.filter_errors"
X.fi
XIf you want to have a copy saved to a file.  A possible strategy would be
Xto have the errors written to a file and to then have a few lines in
Xyour \f2.login\f1 script like:\fC
X.nf
X.ft CW
X.in .5i+\w'if 'u
X.ti .5i
Xif ( -f .filter_errors) then
Xecho  "\ \ "
Xecho "Filter program errors;"
Xcat /tmp/joe.filter_errors
Xecho "\ \ "
X.ti .5i
Xendif\f1
X.in 0
X.ft 1
X.fi
XYou can also use the \f3-v\f1 flag in combination with the above to have
Xa more verbose log file saved by having
Xyour \f2.forward\f1 file;
X.nf
X"| /usr/local/bin/filter -vo /tmp/joe.filter_errors"
X.fi
XSuffice to say, you can get pretty tricky with all this!!
X.ne 5
X.hu Summarizing the Actions Taken
X.sp
XThe \f2Filter\f1 program keeps a log of all actions performed, including
Xwhat rules it matched against, in your home directory in a file
Xcalled \f2.filter_log\f1.  You can either directly operate on this file,
Xor, much more recommended, you can one of the two summarize flags to
Xthe program and let \f2it\f1 do the work for you!
X.sp
XThe difference between the two is best demonstrated by example:
X.nf
X% \f3filter -s\f1
X.ft CW
X.in .5i
X                Summary of Filter Activity
X                \l'\w'Summary of Filter Activity'u-'
XA total of 418 messages were filtered:
XThe default rule of putting mail into your mailbox
X.in .5i+\w'Rule #1: 'u
Xapplied 364 times (87%)
X.ti .5i
XRule #1: (delete message)
Xapplied 1 time (0%)
X.ti .5i
XRule #2: (save in "/users/taylor/Filtered-Mail/netnews.12")
Xapplied 8 times (2%)
X.ti .5i
XRule #3: (save in "/users/taylor/Filtered-Mail/postmaster.12")
Xapplied 14 times (3%)
X.ti .5i
XRule #5: (save in "/users/taylor/Filtered-Mail/risks.12")
Xapplied 3 times (1%)
X.ti .5i
XRule #6: (save in "/users/taylor/Filtered-Mail/rays.12")
Xapplied 28 times (7%)
X.ft 1
X.ti 0
Xversus:
X.ti .5i
X% \f3filter -S\f1
X.ti .5i
X\f2the output as listed above, followed by:\f1
X.ft CW
X.ti .5i
XExplicit log of each action;
X.ti .5i
XMail from taylor about Filter Summary
XPUT in mailbox: the default action
X.ti .5i
XMail from [e-mail] about Newsgroup comp.editors created
XPUT in mailbox: the default action
X.ti .5i
XMail from root about Log file: cleanuplog
XPUT in mailbox: the default action
X.ft 1
X.ti .5i
X[etc etc]
X.in 0
X.ft 1
X.fi
XTo actually use either of the summarizing options, there
Xare two ways that are recommended;
X.sp
XThe preferred way is to have a line in either your \f2crontab\f1
X(ask your administrator for help with this) that invokes the \f2filter\f1
Xprogram as often as you desire with the \f3-s\f1 flag.  For example, I
Xhave a summary mailed to me every morning at 8:00 am:\fC
X.nf
X   0 8 * * * "/usr/local/bin/filter -s | elm -s 'Filter Summary' taylor"
X.fi
X.sp
X\f1An alternative is to have your \f2.login\f1 execute the command each time.
X.sp 2
XNote that if you want to have your log files cleared out each time the
Xsummary is generated you'll need to use the '-c' flag too.  Also,
Xif you want to keep a long list of actions performed you can do this
Xby saving it as you display it.  A way to do this would be, if you were to
Xhave the invocation in your \f2.login\f1 script, to use:\fC
X.nf
X.in .5i
X.ft CW
Xecho "Filter Log;"
Xfilter -c -s | tee -a PERM.filter.log\f1
X.ft 1
X.in 0
X.fi
Xwhich would append a copy of all the output to the file `PERM.filter.log'
Xand would avoid you having to read larger and larger summaries of
Xwhat the program had done.
X.ne 5
X.hu Further Testing of the Ruleset
X.sp
XWith the \f2readmsg\f1 command available, it is quite easy to test the
Xrules you've written to see if they'll do what you desire.
X.sp
XFor example, we can use the \f3-n\f1 flag to \f2filter\f1, which means
X`don't actually do this, just tell me what rule you matched, if any, and
Xwhat action you would have performed' (you can see why a single letter
Xflag is easier to type in!!), and feed it each message in our mailbox
Xby using a command like;
X.nf
X.in .5i
X% \f3set message=1\f1
X% \f3set total_messages=`messages`\f1
X% \f3while  (1)\f1
X> \f3if ($message > $total_messages) exit\f1
X> \f3echo processing message $message\f1
X> \f3readmsg -h $message | filter -n\f1
X> \f3echo " "\f1
X> \f3@ messages++\f1
X> \f3end\f1
X.in 0
X.fi
Xwhich will then hand each of the messages in your mailbox to the \f2filter\f1
Xprogram and display what action would have been taken with that message and
Xwhy.
X.sp
XFor example, if we do this for a few interesting messages in my mailbox,
Xwe'd end up with output like:
X.ft CW
X.nf
X.in .5i
XMail from taylor about filter test
X.ti +\w'Mail 'u
XFORWARDED to hpldat!taylor by rule;
X.ti +\w'Mail   'u
Xsubject="filter test"  ? forward "hpldat!test"
XMail from bradley%hplkab@hplabsc about Re: AI-ED mailing address for HP
X.ti +\w'Mail 'u
XPUT in mailbox: the default action
XMail from taylor about display-to-console
X.ti +\w'Mail 'u
XEXECUTED "cat - > /dev/console"
X.ft 1
X.in 0
X.fi
X(sharp users will notice that this is exactly the same format as the longer
Xsummary listing)
X.ne 5
X.hu What Forwarded Messages Look Like
X.sp
XWhen a message is forwarded to another user by the \f2action\f1 being specified
Xas ``forward \f2address\f1'', then the program can generate one of two styles
Xof message.  If the message is to you, then it'll simply add it to your mailbox
Xin such a way as to ensure that the return address is that of the person who
Xsent the message and so on.
X.sp
XIf not, then the message is enclosed in a message of the form:
X.in \w'If 'u
X.ft CW
X.nf
XFrom taylor Thu Oct  2 15:07:04 1986
XDate: Thu, 2 Oct 86 15:06:58 pdt
XSubject: "filter test"
XFrom: The filter of taylor@hpldat <taylor>
XTo: hpldat!taylor
XX-Filtered-By: filter, version 1.4
X-- Begin filtered message --
X
X.in +\w'-- 'u
XFrom taylor Thu Oct  2 15:06:41 1986
XDate: Thu, 2 Oct 86 15:06:33 pdt
XFrom: Dave Taylor <taylor>
XSubject: filter test
XJust a simple test.
X.in -\w'-- 'u
X-- End of filtered message --
X.ft 1
X.in 0
X.fi
XThe subject of the actual message is the same as the subject of the
Xmessage being forwarded, but in quotes.  The `From:'  field indicates
Xhow the message was sent, and the `X-Filtered-By:' identifies what
Xversion of filter is being used.
X.ne 5
X.hu Areas to Improve
X.sp
XWhile the \f2filter\f1 program as presented herein is obviously a
Xnice addition to the set of tools available for dealing with electronic
Xmail, there are some key features that are missing and will be added in
Xthe future based on demand.
X.sp
XAs I see it, the main things missing are;
X.in .5i
X
X.ti -\n(TWu
X1. The ability to use regular expressions in the patterns.
XThis would be a \f2very\f1 nice feature!
X
X.ti -\n(TWu
X2. Perhaps more \f2actions\f1 available (but what?)
X
X.ti -\n(TWu
X3. Certainly the ability to filter based on any field or combination of
Xfields.
X.in 0
X.ne 5
X.hu Warnings and Things to Look Out For
X.sp
XSince this is a pretty simple program, there are a few pitfalls, some
Xof which have already been mentioned;
X.sp
X\f3Order\f1 counts in the rules.  Beware!
X.sp
X\f3Matching\f1 is pretty simple \(em make sure your patterns are sufficiently
Xexclusive before having any destructive rules.
X.sp 2
XFinally, as with the rest of the \f3Elm\f1 mail system, I welcome feedback
Xand suggestion on how to improve this program!!
SHAR_EOF
echo "File doc/Filter.guid is complete"
chmod 0444 doc/Filter.guid || echo "restore of doc/Filter.guid fails"
echo "x - extracting doc/Form.guide (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/Form.guide &&
X\" @(#)$Id: Form.guide,v 2.8 89/03/29 10:08:51 syd Exp $
X\"
X\"  A guide to using the Elm Forms mode
X\"  format with:
X\"    'troff tmac.n - > Forms.format'
X\"
X\"  Elm is now in the public trust. Bug reports, comments, suggestions, flames
X\"  etc. should go to:
X\"    Syd Weinstein        [e-mail] (dsinc!elm)
X\"
X\"  (C) Copyright 1986, 1987 Dave Taylor
X\"  (C) Copyright 1988, 1989 Usenet Community Trust
X\"
X\"  $Log:    Form.guide,v $
X\" Revision 2.8  89/03/29  10:08:51  syd
X\" First tmac.n checkin
X\"
X\"
X.po 1i
X.ds h0
X.ds h1
X.ds h2
X.ds f0
X.ds f1
X.ds f2
X.nr Hy 1
X.nr Pt 1
X.nr Pi 0
X.lg 0
X.rs
X.de eb
X.sp -1
X.nf
X\h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(ul'
X.fi
X..
X.sp |3.0i
X.ce 99
X.ps 20
X.ss 18
X.vs 12
X\f3Elm Forms Mode Guide\f1
X.sp 7
X.ps 12
X\f2What Forms Mode is, how to use it to create
Xcustom forms, how to reply to forms, and how to
Xuse it for AT&T Mail messages\f1
X.sp 5
XDave Taylor
X.sp
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp 4
X.ps 18
X\f3\(co\f1\s12 Copyright 1986, 1987 by Dave Taylor
X.ps 18
X\f3\(co\f1\s12 Copyright 1988, 1989 by The USENET Community Trust
X.ps 10
X.bp 1
X.sp 5
X.ps 14
X\f3A Guide to Forms Mode in Elm\f1
X.ds h0 "Forms Mode Guide
X.ds h1
X.ds h2 "Version 2.2
X.ds f0
X.ds f1 "Page %
X.sp
X.ps 10
X(Version 2.2)
X.sp
XDave Taylor
X.sp
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp
XApril 1, 1989
X.ce 0
X.sp 2
XWhile there are a lot of mail systems that allow the transmission
Xof text and primitive pictures, to send and reply to more complex
Xforms is simply not possible.  \f3Elm\f1, however, took
Xthe forms mode implemented as part of the AT&T Mail package and has
Xexpanded on it to be a smoothly fit part of the overall mail system.
X.sp
XForms mode gives you the ability to send `template' files to people
Xand receive the filled-in replies.\s-2\u1\d\s0
X.fn
X\f21. note that this feature assumes that the person on the other end
Xis also using the Elm mail system.\f1
X.ef
XLet's look at an example right off.
X.sp
XSay we were going to use computer mail as a way to file defects with
Xsoftware.  There is a certain amount of information we want to be able
Xto collect when each report is made, and if it is in a specific format
Xwe can use programs to file the defects upon receipt.
X.sp
XThe form we'll try to emulate starts out looking like:
X.\" A manual page break has been done because the 'sd' macro doesn't like
X.\" coming up right after the footer or just doesn't like going to a new
X.\" page by itself.  The bug has been reported.
X.bp
X.ft CW
X.sd c
X.mk a
X.sp
X.tl ''Defect Reporting Form''
X.sp
X.tl 'Program:\ \l'2.3i-\w'Program:\ 'u'''Version:\ \l'1.7i-\w'Version:\ 'u''
X.tl 'Operating\ System:\ \l'2.3i-\w'Operating\ System:\ 'u'''Version:\ \l'1.7i-\w'Version:\ 'u''
X.sp
X.tl 'Defect\ Type:\ \l'2.3i-\w'Defect\ Type:\ 'u'''
X.sp
X.tl 'Date\ Found:\ \l'2.3i-\w'Date\ Found:\ 'u'''By\ Whom:\ \l'2.3i-\w'By\ Whom:\ 'u'\h'.2i''
X.tl 'Date\ Reported:\ \l'2.3i-\w'Date\ Reported:\ 'u'''Phone:\ \l'2.3i-\w'Phone:\ 'u'\h'.2i''
X.sp
X.tl 'Description:\ \l'6.4i-\w'Description:\ 'u''
X.tl '\l'6.4i''
X.tl '\l'6.4i''
X.sp
X.eb
X.ed
X.ft 1
X.sp
XThis form can actually be created almost exactly as listed above in
Xthe \f3Elm\f1 mail system by using your standard editor and can then
Xbe mailed about as needed.
X.sp
XLet's say that we want a bit more information, however, especially with
Xfields like ``Defect Type'', we want to list all the recommended answers.
XTo create the actual form, we need merely to replace the underlines in
Xthe above form with spaces.  The multi-line comments can simply be
Xindicated by a `:' by itself on a line;
X
X.ft CW
X.sd c
X.mk a
X.sp
X.tl ''Defect Reporting Form''
X.sp
X.tl 'Program:''Version:\h'1.7i-\w'Version:'u''
X.tl 'Operating System:''Version:\h'1.7i-\w'Version:'u''
X.sp
X.tl '(Valid Defect Types are: user-error, doc-error, fatal, other)'
X.tl 'Defect Type:''
X.sp
X.tl 'Date Found:''By\ Whom:\h'2.3i-\w'By\ Whom:'u''
X.tl 'Date Reported:''Phone:\h'2.3i-\w'Phone:'u''
X.sp
X.tl 'Description'
X.tl ':'
X.sp
XThank you for filling in this form.
X.sp 2
X.eb
X.ed
X.ft 1
X.sp
XAs we can see, it is quite simple to create forms!!
X.sp 2
XNow that we have an idea what we're talking about, let's actually officially
Xdefine the system...
X.br
X.ne 5
X.hu Forms Mode Specification
X
X[Note that this is all taken from the document \f2Standard for Exchanging
XForms on AT&T Mail\f1, Version 1.9 of 6/7/86, from AT&T]
X.sp
XThe forms mode is really quite simple.  Simple enough that it is amazing
Xthat it hadn't been implemented before AT&T Mail came along!!
X.sp
XIn a nutshell, each field is delimited by a `:' followed by a number of
Xblank spaces or tabs that represent the valid size for that field.  That
Xis, if we have a line in the form like;
X.nf
X.ti .5i
X``Phone (area-code):\0\0\0\0\0Number:\0\0\0\0\0\0\0\0\0\0''
X.fi
XThe area-code field will be limited to three characters and the number to nine.
X(this is kind of hard to see with the proportionally spaced formatted copy,
Xalas).
XThe only exception to the rule is that a `:' by itself on a line represents
Xa field that is as large as the user entering the data desires.
X
XThe actual form that is transmitted, in AT&T Mail parlance, is a ``SIMPLE''
Xforms handler message (as opposed to the ``ADVANCED'' handler).  This means
Xthat it contains three sections;
X.br
X.ne 8
X.nf
X.in .5i
X\f2The Message Header\fC
X[OPTIONS-SECTION]
X***
X[FORMS-IMAGE]
X***
X[RULES-SECTION]\f1
X.in 0
X.fi
X\f3Elm\f1 generates form messages with the ``options'' section filled out,
Xbut ignores it when receiving mail.  The filled out section is:\fC
X.nf
X.in .5i
XWIDTH=80
XTYPE=SIMPLE
XOUTPUT=TEXT\f1
X.in 0
X.fi
XThe FORMS-IMAGE section is that described above.  The RULES-SECTION can
Xcontain explicit rules about the possible values of each field, but
Xthis is currently ignored by \f3Elm\f1, being a ``SIMPLE'' forms mode
Xmail system.
X.sp
XForms also have the header ``Content-Type: mailform'' to indicate to the
Xmail system (either \f3Elm\f1 or AT&T Mail) that a form is being sent.
X.sp
X\f3Elm\f1 further indicates that a form has been received by having an
X``F'' as the status character in the header display section (instead of
X``N'' for new, etc).
X.br
X.ne 5
X.hu Composing and Sending a Form
X
XThe first step to enable sending forms is to change the setting of
Xthe variable \f2forms\f1 in your \f2.elmrc\f1 file to ``ON''.  E.g.:
X.nf
X.ti .5i
Xforms = ON
X.fi
XThe next step is to send the message to someone using the `m' (\f2mail\f1)
Xcommand.  This then will drop you into an editor.  Type in the form as
Xindicated above, with appropriate colons and comments, and end the entry
Xby leaving the editor.
X.sp
XThe prompt is now;
X.nf
X.ft CW
X.tl ''Choose: E)dit msg, edit H)eaders, M)ake form, S)end or F)orget : @''
X.ft 1
X.fi
Xso we choose `m' \(em \f2Make form\f1.  The program then will either
Xrewrite the prompt without the M)ake form option, indicating that
Xthe form has been accepted, or will indicate the problem and give you
Xa chance to correct it.
X.sp
XOnce it has been accepted, simple use the `s' \(em \f2send message\f1 -
Xcommand and it's off!
X.sp
X\f2Note that you cannot reply to a message with a Form.\f1
X.br
X.ne 6
X.hu Replying to a Form
X
XLet's reply to the form message we generated now.  The header page of the
X\f3Elm\f1 mail system will indicate that the message is a form by having
Xan `F' next to it.  So we use `r' to reply and the screen is immediately
Xcleared and we're prompted, field by field, for the data requested.
XEach field has underscores in the input area to indicate the size field that
Xis expected.
X.sp
XAfter answering all the questions we'll have a screen that looks like;
X
X.ft CW
X.sd c
X.mk a
X.sp
X.tl ''Defect Reporting Form''
X.sp
X Program:  \f3The Elm Mail System\f1\l'3i-\w'\f3The Elm Mail System'u'
X Version:  \f31.5\f1\l'3i-\w'\f31.5'u'
X Operating System:  \f3HP-UX\f1\l'3i-\w'\f3HP-UX'u'
X Version:  \f35.141 C\f1\l'3i-\w'\f35.141 C'u'
X.sp
X (Valid Defect Types are: user-error, doc-error, fatal, other)
X Defect Type:  \f3fatal\f1\l'5i-\w'\f3fatal\f1'u'
X.sp
X Date Found:  \f310/9/86\f1\l'3i-\w'\f310/9/86\f1'u'
X By Whom:  \f3Dave Taylor\f1\l'3i-\w'\f3Dave Taylor\f1'u'
X Date Reported:  \f310/9/86\f1\l'3i-\w'\f310/9/86\f1'u'
X Phone:  \f3(415) 857-6887\f1\l'3i-\w'\f3(415) 857-6887\f1'u'
X.sp
X Description
X (Enter as many lines as needed, ending with a `.' by itself on a line)
X   \f3When running it on a CPM system I cannot compile successfully.\f1
X   \f3.\f1
X Thank you for filling in this form.
X.tl ''Choose: E)dit form, edit H)eaders, S)end or F)orget : @''
X.sp
X.eb
X.ed
X.ft 1
X.sp
XQuite simple.  Notice, however, that the order of prompting is left to
Xright on each line, so the fields that on the form are placed in what
Xseems like a logical place, ``By Whom:'' and ``Phone:'' turn out to be
Xconfusing when filling in the actual form since it isn't clear what
X``Phone:'' is being asked for because of the intervention of the
X``Date Reported:'' field.
X.sp
XThe message that will actually be sent out from this will have the
Xfields in a more acceptable format;
X.\" Force page break, as there seems to be a bug in the .sd macro
X.bp
X.\"
X.ft CW
X.mk a
X.sp
X WIDTH=80
X TYPE=SIMPLE
X OUTPUT=TEXT
X ***
X.tl ''Defect Reporting Form''
X.sp
X.tl ' Program: The Elm Mail System''Version: 1.5\h'1.5i-\w'Version: 1.5'u''
X.tl ' Operating System: HP-UX''Version: 5.141 C\h'1.5i-\w'Version: 5.141 C'u''
X.sp
X.tl ' (Valid Defect Types are: user-error, doc-error, fatal, other)'
X.tl ' Defect Type: fatal''
X.sp
X.tl ' Date Found: 10/9/86''By Whom: Dave Taylor\h'2.3i-\w'By Whom: Dave Taylor'u''
X.tl ' Date Reported: 10/9/86''Phone: [phone]\h'2.3i-\w'Phone: [phone]'u''
X.sp
X.tl ' Description'
X.sp
X    When running it on a CPM system I cannot compile successfully.
X.sp
X.tl ' Thank you for filling in this form.'
X ***
X.sp
X.eb
X.ft 1
X
X.hu Comments on Forms Mode
X
XAs was said at the beginning, this way of sending about forms could
Xprove to be very helpful and useful in a variety of contexts.  On the
Xother hand, until a more sophisticated forms language is used for the
Xforms, this should be sufficient to embody the power of the idea.
X.sp
XI welcome any comments and thoughts on this system and also welcome
Xpossible enhancements.
X.sp
XI also gratefully thank Dale DeJager of AT&T Information Systems
Xfor sending me more
Xinformation on AT&T Mail than I could possibly digest in any finite
Xamount of time.
SHAR_EOF
chmod 0444 doc/Form.guide || echo "restore of doc/Form.guide fails"
echo "x - extracting doc/Makefile.SH (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/Makefile.SH &&
Xcase $CONFIG in
X'')
X    if test ! -f config.sh; then
X    ln ../config.sh . || \
X    ln ../../config.sh . || \
X    ln ../../../config.sh . || \
X    (echo "Can't find config.sh."; exit 1)
X    fi
X    . ./config.sh
X    ;;
Xesac
Xcase "$0" in
X*/*) cd `expr X$0 : 'X\(.*\)/'` ;;
Xesac
X
Xecho "Extracting doc/Makefile (with variable substitutions)"
Xcat >Makefile <<!GROK!THIS!
X#
X# $Id: Makefile.SH,v 2.8 89/03/30 16:01:35 syd Exp $
X#
X#  Makefile for the documentation of the ELM mail system
X#
X#         (C) Copyright 1989, USENET Community Trust
X#
X#  $Log:    Makefile.SH,v $
X# Revision 2.8  89/03/30  16:01:35  syd
X# First tmac.n checkin
X#
X#
X# Variables
X#    Variables established by Configure
XCHMOD        =    $chmod
XCP        =    $cp
XDEST        =    $bin
XECHO        =    $echo
XFORMATTER    =    $roff
XLIB        =    $lib
XLN        =    $ln
XMAN        =    $mansrc
XMANEXT        =    $manext
XRM        =     $rm -f
XTBL           =    $tbl
X!GROK!THIS!
X
Xcat >>Makefile <<'!NO!SUBS!'
X
X#    Other variables
XSHELL        =    /bin/sh
X
X# List of installed man pages (except for wnemail.1 - handled differently)
XMAN_LIST        =    $(MAN)/answer.$(MANEXT)        \
X                $(MAN)/autoreply.$(MANEXT)    \
X                $(MAN)/checkalias.$(MANEXT)    \
X                $(MAN)/elm.$(MANEXT)        \
X                $(MAN)/fastmail.$(MANEXT)    \
X                $(MAN)/filter.$(MANEXT)        \
X                $(MAN)/frm.$(MANEXT)        \
X                $(MAN)/listalias.$(MANEXT)    \
X                $(MAN)/messages.$(MANEXT)    \
X                $(MAN)/newalias.$(MANEXT)    \
X                $(MAN)/printmail.$(MANEXT)    \
X                $(MAN)/readmsg.$(MANEXT)
X
X# List of remotely installed man pages (except for wnemail.1 - handled
X# differently)
XREMOTE_MAN_LIST        =    $(REMOTE)$(MAN)/answer.$(MANEXT)    \
X                $(REMOTE)$(MAN)/autoreply.$(MANEXT)    \
X                $(REMOTE)$(MAN)/checkalias.$(MANEXT)    \
X                $(REMOTE)$(MAN)/elm.$(MANEXT)        \
X                $(REMOTE)$(MAN)/fastmail.$(MANEXT)    \
X                $(REMOTE)$(MAN)/filter.$(MANEXT)    \
X                $(REMOTE)$(MAN)/frm.$(MANEXT)        \
X                $(REMOTE)$(MAN)/listalias.$(MANEXT)    \
X                $(REMOTE)$(MAN)/messages.$(MANEXT)    \
X                $(REMOTE)$(MAN)/newalias.$(MANEXT)    \
X                $(REMOTE)$(MAN)/printmail.$(MANEXT)    \
X                $(REMOTE)$(MAN)/readmsg.$(MANEXT)
X
X# List of files installed in LIB directory
XLIB_LIST        =    $(LIB)/elm-help.0    \
X                $(LIB)/elm-help.1    \
X                $(LIB)/elm-help.2    \
X                $(LIB)/elm-help.3    \
X                $(LIB)/elmrc-info
X
X# List of files installed in remote LIB directory
XREMOTE_LIB_LIST        =    $(REMOTE)$(LIB)/elm-help.0    \
X                $(REMOTE)$(LIB)/elm-help.1    \
X                $(REMOTE)$(LIB)/elm-help.2    \
X                $(REMOTE)$(LIB)/elm-help.3    \
X                $(REMOTE)$(LIB)/elmrc-info
X
X# List of formatted guides
XFORMATTED_LIST        =    Alias.fmtd    \
X                Config.fmtd     \
X                Cover.fmtd    \
X                Filter.fmtd    \
X                Form.fmtd    \
X                Ref.fmtd    \
X                Users.fmtd
X
X# Targets
X#    The following are no-ops
Xall:
Xlint:
Xclean:
X
Xinstall:    $(LIB_LIST) $(MAN_LIST) $(MAN)/wnewmail.$(MANEXT)
X
X#    Dependencies and rules for installing man pages and lib files
X#    taken from a remote system
X#    This is the only target that gets installed even if not out-of-date
X#    with respect the files from which it is installed.
Xrmt-install:    rmt-defined
X        $(RM) $(MAN)/newmail.$(MANEXT) $(MAN)/wnewmail.$(MANEXT)
X        $(CP) $(REMOTE_MAN_LIST) $(MAN)
X        $(CHMOD) u+w,a+r $(MAN_LIST)
X        $(LN) $(MAN)/newmail.$(MANEXT) $(MAN)/wnewmail.$(MANEXT)
X        $(CP) $(REMOTE_LIB_LIST) $(LIB)
X        $(CHMOD) u+w,a+r $(LIB_LIST)
X
Xrmt-defined:
X    @(if [ "$(REMOTE)" = "" ];\
X      then\
X        $(ECHO) "You need to define 'REMOTE' as the remote file system";\
X        $(ECHO) "for this particular command. The easiest way to do this";\
X        $(ECHO) "to type:";\
X        $(ECHO) "        make REMOTE=<remote file system> rmt-install";\
X        exit 1;\
X      fi);
X
X#    Dependencies and rules for installing man pages and lib files
X$(MAN)/answer.$(MANEXT):    answer.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/autoreply.$(MANEXT):    autoreply.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/checkalias.$(MANEXT):    chkalias.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/elm.$(MANEXT):        elm.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/fastmail.$(MANEXT):    fastmail.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/filter.$(MANEXT):    filter.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/frm.$(MANEXT):        frm.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/listalias.$(MANEXT):    listalias.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/messages.$(MANEXT):    messages.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/newalias.$(MANEXT):    newalias.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/newmail.$(MANEXT):    newmail.1
X                $(RM) $@
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/printmail.$(MANEXT):    printmail.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/readmsg.$(MANEXT):    readmsg.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(MAN)/wnewmail.$(MANEXT):    $(MAN)/newmail.$(MANEXT)
X                $(RM) $@
X                $(LN) $? $@
X
X$(LIB)/elm-help.0:        elm-help.0
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(LIB)/elm-help.1:        elm-help.1
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(LIB)/elm-help.2:        elm-help.2
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(LIB)/elm-help.3:        elm-help.3
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X$(LIB)/elmrc-info:        elmrc-info
X                $(CP) $? $@
X                $(CHMOD) u+w,a+r $@
X
X#    Dependencies and rules for formatting guides
Xdocumentation:    $(FORMATTED_LIST)
X
XAlias.fmtd:    Alias.guide
X        $(TBL) $? | $(FORMATTER) tmac.n - > $@
X
XConfig.fmtd:    Config.guid
X        $(TBL) $? | $(FORMATTER) tmac.n - > $@
X
XCover.fmtd:    Elm.cover
X        $(FORMATTER) tmac.n $? > $@
X
XFilter.fmtd:    Filter.guid
X        $(TBL) $? | $(FORMATTER) tmac.n - > $@
X
XForm.fmtd:    Form.guide
X        $(FORMATTER) tmac.n $? > $@
X
XRef.fmtd:    Ref.guide
X        $(FORMATTER) tmac.n $? > $@
X
XUsers.fmtd:    Users.guide
X        $(TBL) $? | $(FORMATTER) tmac.n - > $@
X!NO!SUBS!
SHAR_EOF
chmod 0444 doc/Makefile.SH || echo "restore of doc/Makefile.SH fails"
echo "x - extracting doc/Ref.guide (Text)"
sed 's/^X//' << 'SHAR_EOF' > doc/Ref.guide &&
X\" @(#)$Id: Ref.guide,v 2.23 89/03/31 11:19:34 syd Exp $
X\"
X\"  Reference guide to the Elm mail system.
X\"  format with
X\"      troff tmac.n Ref.guide > Ref.format
X\"
X\"  Elm is now in the public trust. Bug reports, comments, suggestions, flames
X\"  etc. should go to:
X\"    Syd Weinstein        [e-mail] (dsinc!elm)
X\"
X\"  (C) Copyright 1986, 1987 Dave Taylor
X\"  (C) Copyright 1988, 1989 Usenet Community Trust
X\"
X\"  $Log:    Ref.guide,v $
X\" Revision 2.23  89/03/31  11:19:34  syd
X\" Release 2.2 checkin
X\"
X\"
X.po 1i
X.ds h0
X.ds h1
X.ds h2
X.ds f0
X.ds f1
X.ds f2
X.nr Hy 1
X.nr Pt 1
X.nr Pi 0
X.lg 0
X.rs
X.za
X.sp |3.0i
X.ce 99
X.ps 20
X.ss 18
X.vs 12
X\f3The Elm Reference Guide\f1
X.sp 5
X.ps 12
X\f2A comprehensive list of all commands,
Xoptions and such to the \f3Elm\fP mail system\f1
X.sp 5
XDave Taylor
X.sp
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: [e-mail] or hplabs!taylor
X.sp 4
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp 4
X.ps 18
X\f3\(co\f1\s12 Copyright 1986, 1987 by Dave Taylor
X.ps 18
X\f3\(co\f1\s12 Copyright 1988, 1989 by The USENET Community Trust
X.ce 0
X.bp 1
X.ce 99
X.ps 14
X\f3The Elm Reference Guide\f1
X.ds h0 "Elm Reference Guide
X.ds h1
X.ds h2 "Version 2.2
X.ds f0
X.ds f1 "Page %
X.sp
X.ps 10
X(Version 2.2)
X.sp 2
XDave Taylor
XHewlett-Packard Laboratories
X1501 Page Mill Road
XPalo Alto CA
X94304
X.sp
Xemail: [e-mail] or hplabs!taylor
X.sp 2
X>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
X.sp
XSyd Weinstein
XDatacomp Systems, Inc.
X3837 Byron Road
XHuntingdon Valley, PA 19006-2320
X.sp
Xemail: elm\s-1@\s+1dsinc.UUCP  or  dsinc\s-1!\s+1elm
X.sp 2
XApril 1, 1989
X.ce 0
X.sp 3
X.hn 1 Introduction
X
XThere are many parts to a complex software system and \f3The Elm
XMail System\f1
Xis no different.  This document describes fully all the options
Xavailable in the mailer, including the command line options,
Xthe commands (in considerably more detail than
Xin \f2The Elm Users Guide\f1) and
Xthe \f2.elm/elmrc\f1 file.
X
XTo be more explicit, this document covers:
Xa discussion of
Xthe \f2.elm/elmrc\f1 file,
Xcommand line options of \f2elm\f1,
Xoutgoing mail processing,
Xresponses of various commands,
Xmail archive folders,
Xthe Alias system,
Xsystem aliases etc,
Xmore on the \f3Elm\f1 utilities,
Xand a section for expert mail users.
X
XWithout any further ado, then, let's get this show on the road!!
X.sp
X.hn 1 "The .elm/elmrc File"
X
XElm, like lots of other software on the
XUnix\v'-.3'\s5TM\s10\v'.3' system, has the ability to automatically read
Xin a configuration file at each invocation.  The file must be
Xcalled \f2elmrc\f1 and reside in the \f2.elm\f1 directory located
Xin your home directory.  It can have any of the entries below, in any order.
XIf you are missing any entries, or if you don't have an \f2.elm/elmrc\f1
Xfile, the default values (listed below for each option) will be used.
XNote that those options below designated with * can be altered
Xusing elm via the o)ptions screen.
XAlso note that when you save a new \f2.elm/elmrc\f1 file via the `>' command
Xof the options
Xscreen, it will be (re)created including even those options that
Xhave default values.
X.br
X.sp
X.ne 8
X.hu String Variables
X
X.lp alternatives 1.0i
XThis is a list of other machine/username combinations
Xthat you receive mail from (forwarded).  This is used
Xwhen the \f2group reply\f1 feature is invoked to ensure that
Xyou don't send yourself a copy of the outbound message.
X(The default is a list of no alternatives.)
X
X.lp calendar* 1.0i
XThis is used in conjunction with the `<' \f2scan message for
Xcalendar entries\f1 command, as the file to append any found
Xcalendar entries to.  (The default is \f2calendar\f1 in your home directory.)
X
X.lp editor* 1.0i
XThe editor to use when typing in new mail.  If you select
X``none'' or ``builtin'' you'll get a Berkeley Mail style
Xinterface for all mail that doesn't already have text
Xin the buffer (e.g. a reply, mail with a ``signature'', etc).
X(The default is to use the value of $EDITOR in your
Xcurrent environment, and if not set, an editor selected by
Xthe person who configured \f2elm\f1 for your system.)
X
X.lp escape 1.0i
XThe character used with the ``builtin'' editor (see above)
Xto escape from text entry to input a command.
XWhen a line begins with this character, the editor interprets it
Xas a command rather than as text to add.
X(The default is ``~''.)
X
X.lp fullname* 1.0i
XThis is the name the mailer will use in messages
Xyou send.  It is highly recommended that you use your
Xfull name and nothing strange or unusual, as that can
Xappear extremely rude to people receiving your mail.
X(The default is to use the ``gcos'' field from the \f2/etc/passwd\f1 file
Xon systems that use this field to store full names, and to use the contents
Xof \f2.fullname\f1 in your home directory on other systems.)
X
X.lp maildir* 1.0i
XThis is your folder directory.
XWhen you specify a folder name beginning with the `=' metacharacter\s-2\u1\d\s0,
X.fn
X1. Note that `%' and `+' are synonymous with `=' throughout \f2elm\f1
X.ef
Xit stands for this directory name.  That is,
Xif you save a message to folder \f2=stuff\f1
Xthe `=' will be expanded to the current value of \f2maildir\f1.
X(The default is the directory \f2Mail\fP in your home directory.)
X
X.lp pager 1.0i
XThis is the program to be used to display messages.  You can
Xspecify ``builtin'' or the name of any standard pager.  If you
Xuse ``builtin+'', each screenfull of displayed message is
X``paged'' from the top of your screen with a title line,
Xwhile ``builtin'' simply ``scrolls up'' subsequent screenfulls once
Xit has ``paged'' the first screenfull.
X(The default is to use the value of $PAGER in your
Xcurrent environment, and if not set, a pager selected by
Xthe person who configured \f2elm\f1 for your system, quite likely ``builtin+''.)
X
X.lp prefix 1.0i
XWhen you \f2reply\f1 to a message or \f2forward\f1 a message to another person,
Xyou can optionally include the original message.  Defining the
Xprefix value here allows you to indicate what the prefix of
Xeach included line should be.  (The default is ``>\ '' and is
Xstandard in the Unix community.)
X
X.lp print* 1.0i
XThis is the command used for printing messages.  There are two
Xpossible formats for it, either a command that
Xcan have a filename affixed to (as a suffix) before being
Xexecuted, or a string that
Xcontains the meta-sequence `%s' which will be replaced
Xby the name of the file before being executed.  Examples of each are:
X.nf
X.ft CW
X    print = print -formfeed
X    print = pr %s | lpr
X.ft 1
X.fi
X(The default is set by the person who configured \f2elm\f1 for your system.)
X
X.lp receivedmail 1.0i
XThis is the folder to which incoming mail is saved after you've read it.
XWhen you answer \f2no\f1 (`n') to the ``keep unread messages in
Xyour incoming mailbox?'' prompt or \f2yes\f1 (`y') to the ``store read
Xmessages in your "received" folder?'', this is where the messages go.
X(The default is "=received", that is,
Xa folder called \f2received\f1 in your \f2maildir\f1 directory).
X
X.lp sentmail* 1.0i
XThis is the folder to which a copy of outgoing mail is automatically
Xsaved.  This will only be done if the \f2copy\f1 flag
Xis turned on (see below).  Also note that if the \f2savename\f1 feature
X(see below) is enabled then this folder will be ignored since the program
Xwill save to a folder that has the same name as the login
Xof the person you're sending to.
XWhether or not a copy is saved, and to what folder, can be changed just
Xprior to sending a message, see below.
X(The default is "=sent", that is,
Xa folder called \f2received\f1 in your \f2maildir\f1 directory).
X
X.lp shell 1.0i
XThis defines the shell to use when doing ``!'' escapes and
Xsuch.  (The default is to use the value of $SHELL in your
Xcurrent environment, and if not set, a shell selected by
Xthe person who configured \f2elm\f1 for your system.)
X
X.lp signature 1.0i
XThis file, if defined, will be automatically appended to all
Xoutbound mail before the editor is invoked.  Furthermore,
Xif you'd like a different ``.signature'' file for \f2local\f1
Xmail and \f2remote\f1 mail (remote being via other hosts),
Xyou can alternatively define two variables, \f2localsignature\f1
Xand \f2remotesignature\f1, to have the same functionality.
X(The default is "localsignature" and "remotesignature" in the \f2.elm\f1
Xdirectory in your home directory.)
X
X.lp sortby* 1.0i
XYou can have your folder sorted by any of the following ways:
X.sp
X.ta 1i
Xfrom    This will sort according to whom each message is \f2from\f1.
X
Xlines    This will sort \f2shortest\f1 to \f2longest\f1 by message.
X
Xmailbox    This will leave the messages in the order found in the folder.
X
Xreceived    This will sort \f2least recently received\f1 to
X\f2most recently received\f1.
X
Xsent    This will sort \f2least recently sent\f1 to \f2most recently sent\f1.
X
Xstatus    This will sort by priority, action, new, tagged, then deleted.
X
Xsubject    This will sort according to the \f2subject\f1 of each message.
X.sp
XEach of these fields can also optionally be prepended with the
Xsequence ``reverse-'' to reverse the order of the sort.  This doesn't
Ximply anything about the order of the message in the folder
Xitself and affects only their order on the index screen.  (The
Xdefault is \f2mailbox\f1 order.)
X
X.lp weedout 1.0i
XWhen specifying this option, you can list headers that
Xyou \f2don't\f1 want to see when you are displaying a message.
XThis list can continue for as many lines as desired, as
Xlong as the continued lines all have leading indentation.
X(The default is ``Received:'' and others.)
X.br
X.ne 8
X.hu Numeric Variables
X
X.lp bounceback 1.0i
XThis is a hop count threshold value and allows you to
Xset up the mailer so that when you send mail more than
X\f2n\f1 machines away, it'll automatically include a
X``Cc:'' to you through the remote machine.  In practice
Xthis should be very rarely used.  (Note: this refuses to
Xbounce mail off an Internet address.  The default is to
Xhave it set to zero, which disables the function)
X
X.lp timeout 1.0i
XOn more advanced systems, it's nice to start up the
Xmailer in a window and let it sit in background
Xunless new mail arrives (see \f2wnewmail\f1 for
Xanother window based program) at which point
Xit can be brought up to the forefront of the system
Xand read.  In this case, it would be quite convenient
Xto have the mailer internally resynchronize every
Xso often.  This option specifies the number of seconds that this occurs.
X.sp
XThis is also useful for normal terminals, for example you can
Xleave \f2elm\f1 running at night (I usually do) and when you
Xcome in in the morning it'll be all ready to read your mail!
X.sp
X(The default is a 300 second (5 minute) timeout period).
X
X.lp userlevel* 1.0i
XThis is what the program uses to determine the relative level of
Xsophistication of the user \(em the values are 0 for a new user (the
Xdefault), 1 for someone familiar with \f2elm\f1
Xuser, and 2 for experts.  Some advanced features are hidden from novice
Xusers, while experts get less verbose prompt messages.
X.br
X.ne 8
X.hu Boolean Variables
X
X.lp alwaysdelete 1.0i
XWhen set, this changes the default answer
Xof the prompt ``Delete messages?'' to the indicated value.  (The default is
Xto have the answer be \f2No\f1 (i.e. alwaysdelete = OFF).)
X
X.lp alwaysstore 1.0i
XThis sets the default
Xanswer on the ``store read mail in "received" folder'' prompt
Xto the value indicated.  (The default is to have the default
Xanswer be \f2No\f1 (i.e., alwaysstore = OFF).)
X
X.lp alwayskeep 1.0i
XThis sets the default answer
Xon the ``keep unread mail in incoming mailbox''
XHowever, if you answered \f2No\fP to the ``store read
Xmail in "received" folder''
Xit is presumed that you'd also want to keep your unread mail in the
Xincoming mailbox, too, and the value of alwayskeep is ignored.
X(The default is to have the
Xdefault answer be \f2Yes\f1 (i.e., alwayskeep = ON).)
X
X.lp arrow* 1.0i
XSometimes your are forced to use a slow, or ``dumb'' terminal.  In this
Xcase, you can force the current message pointer to be the ``->''
Xsequence rather than the inverse bar.  (Note that this is
Xoverridden by the similar `-a' command line option,
Xsee below.)  (The default is OFF.)
X
X.lp ask 1.0i
XThis allows you to tell the \f2elm\f1 system that
Xyou'd rather not be asked ``Delete Mail?'' and such each time you
Xresynchronize a folder or change folders,
Xand instead it should just use the values of
X``alwaysdelete'', ``alwaysstore'', and ``awayskeep'' without prompting.
XNote that when you quit \f2elm\fP, if you use `q', you will be asked
Xthese questions, and if you use `Q', you won't.
X(The default is ON, i.e. to ask the questions.)
X
X.lp askcc 1.0i
XIf turned off, this will allow you to send mail without being
Xpresented the ``Copies to:'' prompt for each message. This
Xstill allows you to explicitly include addresses in the ``cc''
Xlist via either ``~c'' in the builtin editor, or via using the
Xheader editor.  (The default is ON, i.e. to ask about copies.)
X
X.lp autocopy 1.0i
XIf turned on, this will automatically copy
Xthe text of each message being replied to into the edit
Xbuffer.  Otherwise you will be prompted as to whether you want
Xthe message included in yours. (See the \f2prefix\f1
Xoption above.)  (The default is OFF.)
X
X.lp copy 1.0i
XThis, in combination with the \f2sentmail\f1 folder, will
Xallow you to have silent copies of all outgoing mail
Xmade on the outbound step.
XWhether a copy is saved and to which folder can be set prior to sending
Xa message, see below.
X(The default is OFF.)
X
X.lp keep 1.0i
XThe mail system has a habit of deleting folders when you've
Xremoved everything from them.  With this option turned on, it will
Xinstead preserve them as zero-byte files.
XThis option does not apply to your incoming mailbox.
X(The default is OFF.)
X
X.lp keypad 1.0i
XIf on, this tells \f2elm\f1 that you have an HP terminal and enables
Xthe <NEXT>, <PREV>, <HOME> and <SHIFT-HOME> keys.  (The default is OFF.)
X
X.lp menus* 1.0i
XIf turned off, this will inhibit the Menu display on all of the
Xscreen displays within the \f2elm\f1 program.  (Note that this is
Xoverridden by the similar `-m' command line option,
Xsee below.)  (The default is ON.)
X
X.lp names* 1.0i
XIf turned off, the primary recipients' address is displayed on your
Xscreen with their full names when you send a message.  Otherwise,
Xonly the full names are given.  (The default is ON.)
X
X.lp movepage 1.0i
XIf this is enabled then commands that move through the
Xfolder by pages (the `+', `-', <right-arrow>, and <left-arrow> keys)
Xwill also move the current message pointer to the
Xtop of that page of messages.  If this is turned off
Xthen moving through the pages doesn't alter the
Xcurrent message pointer location.
X(The default is OFF.)
X
X.lp noheader 1.0i
XThis boolean flag tells the mailer not to include the
Xheaders of messages when copying a message into a file
Xbuffer for replying to or forwarding.
X(The default is ON.)
X
X.lp promptafter 1.0i
XIf this flag is ON and you use an external pager,
Xwhen the pager exits, you will be prompted for a command rather
SHAR_EOF
echo "End of part 4"
echo "File doc/Ref.guide is continued in part 5"
echo "5" > s2_seq_.tmp
exit 0